Margin Money Receipt OCR API

The following document highlights the details of the Margin Money Receipt OCR API.

API Description

Objective

The Margin Money Receipt OCR API extracts the textual data from an image of a receipt document and returns it in a JSON format.

Input	Output
An image or PDF file containing the margin money receipt document.	The textual information extracted from the document.

API URL

https://ind-engine.thomas.hyperverge.co/v1/readMRR

API Endpoint

readMRR

Overview

The Margin Money Receipt OCR API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	multipart/form-data
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the Margin Money Receipt OCR API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
image	Mandatory	string	The image or PDF file containing the margin money receipt document	JPG, JPEG, PNG, or PDF	Not Applicable

Caution

• If you send multiple files in the same API request, the OCR extraction will be performed only on one of the files. Kindly send only one file in a request to avoid confusion.
• If the PDF file has multiple pages, only the first page will be considered for the OCR extraction.

Request

The following code snippet demonstrates a standard curl request for the Margin Money Receipt OCR API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/readMRR' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'image=@"<path_to_image_file>"'

Success Response

The following code snippet demonstrates a success response from the Margin Money Receipt OCR API:

{
  "status": "success",
  "statusCode": "200",
  "result": [
    {
      "details": {
        "customerName": {
          "value": "<Customer_Name>"
        },
        "amountInFigures": {
          "value": "<Amount_In_Figures>"
        },
        "amountInWords": {
          "value": "<Amount_In_Words>"
        },
        "dealerName": {
          "value": "<Dealer_Name>"
        },
        "receiptNumber": {
          "value": "<Receipt_Number>"
        },
        "receiptDate": {
          "value": "<Receipt_Date_in_DD/MM/YYYY_Format>"
        }
      }
    }
  ],
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Caution

When the image is not of a valid margin money receipt document, the JSON output might contain null or random values.

Success Response Details

The following table outlines the details of the success response from the Margin Money Receipt OCR API:

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The HTTP status code for the response
result	array	An array containing the extracted details from the margin money receipt document
result[].details	object	The object containing the extracted fields from the document
result[].details.customerName	object	The customer name extracted from the document
result[].details.customerName.value	string	The value of the customer name
result[].details.amountInFigures	object	The amount in figures extracted from the document
result[].details.amountInFigures.value	string	The value of the amount in figures
result[].details.amountInWords	object	The amount in words extracted from the document
result[].details.amountInWords.value	string	The value of the amount in words
result[].details.dealerName	object	The dealer name extracted from the document
result[].details.dealerName.value	string	The value of the dealer name
result[].details.receiptNumber	object	The receipt number extracted from the document
result[].details.receiptNumber.value	string	The value of the receipt number
result[].details.receiptDate	object	The receipt date extracted from the document
result[].details.receiptDate.value	string	The value of the receipt date in DD/MM/YYYY format
metaData	object	The object containing metadata information
metaData.requestId	string	The unique identifier associated with the request
metaData.transactionId	string	The unique identifier for the transaction

Error Responses

The following are some error responses from the Margin Money Receipt OCR API:

Missing Input File

{
    "status": "failure",
    "statusCode": 400,
    "error": "API call requires one input image",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

No Image Input

{
    "status": "failure",
    "statusCode": 400,
    "error": "No Image input",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid Image Size

{
    "status": "failure",
    "statusCode": 400,
    "error": "image size cannot be greater than 6 MB",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Undetected Document

{
    "status": "failure",
    "statusCode": 422,
    "error": "Document Not Detected",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Internal Server Error

{
    "status": "failure",
    "statusCode": 500,
    "error": "Internal Server Error",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	API call requires one input image	The request did not contain the mandatory image file input	Provide a valid image file in the request
400	No Image input	The request is missing the image input parameter	Ensure the image parameter is included in the request
400	image size cannot be greater than 6 MB	The uploaded image exceeds the supported size limit of 6MB	Ensure the image file size is 6MB or less
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Provide valid appId and appKey credentials in the request
422	Document Not Detected	No valid document could be detected in the provided image	Ensure the image contains a clear, readable margin money receipt document
500	Internal Server Error	There was an error with HyperVerge's server	Please check the request headers or contact the HyperVerge team for resolution